/* vim: set ts=2 et sw=2 cindent fo=qroca: */

package com.globant.google.mendoza.malbec.transport;

import com.globant.google.mendoza.malbec.CalculationListener;
import com.globant.google.mendoza.malbec.OrderListener;

/** An object that fires a specific notification to the order listener or a
 * merchant calculation request to a calculation listener.
 *
 * Each implementation of this interface decides what notification method to
 * fire on the order listener or the calculation listener.
 */
public interface NotificationFirerer {

  /** Fires a notification event to an order.
   *
   * This notification event is fired after the acknowledge is sent to checkout
   * server.
   *
   * @param transport The transport implementation that will be used by the
   * order.
   *
   * @param listener The order listener that listens to notification events. It
   * is never null.
   */
  void notify(final Transport transport, final OrderListener listener);

  /** Fires a pre-notification event to an order.
   *
   * This notification is sent before the acknowledge is sent to checkout. This
   * is used to fire calculation events. If the object that receives this event
   * throws an exception, the acknowledge is not sent to checkout.
   *
   * @param transport The transport implementation that will be used by the
   * order.
   *
   * @param orderListener The order listener that listens to notification
   * events. It may be null, in wich case no notification will be sent.
   *
   * @param calculationListener The calculation listener that listens to
   * merchant calculation events. It may be null, in wich case no calculation
   * request will be proccesed.
   *
   * @return Returns a Object that can be either a JAXBElement or a String
   * representing the response to checkout.
   * It may be null, in which case it returns an acknowledge to checkout.
   */
  Object preNotify(final Transport transport, final OrderListener
      orderListener, final CalculationListener calculationListener);
}

